<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Jacobi Zeta Function</title>
<link rel="stylesheet" href="../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Math Toolkit 4.2.1">
<link rel="up" href="../ellint.html" title="Elliptic Integrals">
<link rel="prev" href="ellint_d.html" title="Elliptic Integral D - Legendre Form">
<link rel="next" href="heuman_lambda.html" title="Heuman Lambda Function">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ellint_d.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="heuman_lambda.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.ellint.jacobi_zeta"></a><a class="link" href="jacobi_zeta.html" title="Jacobi Zeta Function">Jacobi Zeta Function</a>
</h3></div></div></div>
<h5>
<a name="math_toolkit.ellint.jacobi_zeta.h0"></a>
        <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.synopsis"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.synopsis">Synopsis</a>
      </h5>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">jacobi_zeta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">jacobi_zeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">jacobi_zeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</span>

<span class="special">}}</span> <span class="comment">// namespaces</span>
</pre>
<h5>
<a name="math_toolkit.ellint.jacobi_zeta.h1"></a>
        <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.description"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.description">Description</a>
      </h5>
<p>
        This function evaluates the Jacobi Zeta Function <span class="emphasis"><em>Z(φ, k)</em></span>
      </p>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../equations/jacobi_zeta.svg"></span>

        </p></blockquote></div>
<p>
        Please note the use of φ, and <span class="emphasis"><em>k</em></span> as the parameters, the
        function is often defined as <span class="emphasis"><em>Z(φ, m)</em></span> with <span class="emphasis"><em>m
        = k<sup>2</sup></em></span>, see for example <a href="http://mathworld.wolfram.com/JacobiZetaFunction.html" target="_top">Weisstein,
        Eric W. "Jacobi Zeta Function." From MathWorld--A Wolfram Web Resource.</a>
        Or else as <a href="https://dlmf.nist.gov/22.16#E32" target="_top"><span class="emphasis"><em>Z(x, k)</em></span></a>
        with <span class="emphasis"><em>φ = am(x, k)</em></span>, where <span class="emphasis"><em>am</em></span> is the
        <a href="https://dlmf.nist.gov/22.16#E1" target="_top">Jacobi amplitude function</a>
        which is equivalent to <span class="emphasis"><em>asin(jacobi_elliptic(k, x))</em></span>.
      </p>
<p>
        The return type of this function is computed using the <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
        type calculation rules</em></span></a> when the arguments are of different
        types: when they are the same type then the result is the same type as the
        arguments.
      </p>
<p>
        Requires <span class="emphasis"><em>-1 &lt;= k &lt;= 1</em></span>, otherwise returns the result
        of <a class="link" href="../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>
        (outside this range the result would be complex).
      </p>
<p>
        The final <a class="link" href="../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
        be used to control the behaviour of the function: how it handles errors,
        what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">policy
        documentation for more details</a>.
      </p>
<p>
        Note that there is no complete analogue of this function (where φ = π / 2) as
        this takes the value 0 for all <span class="emphasis"><em>k</em></span>.
      </p>
<h5>
<a name="math_toolkit.ellint.jacobi_zeta.h2"></a>
        <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.accuracy"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.accuracy">Accuracy</a>
      </h5>
<p>
        These functions are trivially computed in terms of other elliptic integrals
        and generally have very low error rates (a few epsilon) unless parameter
        φ
is very large, in which case the usual trigonometric function argument-reduction
        issues apply.
      </p>
<div class="table">
<a name="math_toolkit.ellint.jacobi_zeta.table_jacobi_zeta"></a><p class="title"><b>Table 8.68. Error rates for jacobi_zeta</b></p>
<div class="table-contents"><table class="table" summary="Error rates for jacobi_zeta">
<colgroup>
<col>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
              </th>
<th>
                <p>
                  GNU C++ version 7.1.0<br> linux<br> double
                </p>
              </th>
<th>
                <p>
                  GNU C++ version 7.1.0<br> linux<br> long double
                </p>
              </th>
<th>
                <p>
                  Sun compiler version 0x5150<br> Sun Solaris<br> long double
                </p>
              </th>
<th>
                <p>
                  Microsoft Visual C++ version 14.1<br> Win32<br> double
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  Elliptic Integral Jacobi Zeta: Mathworld Data
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 0ε (Mean = 0ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 1.66ε (Mean = 0.48ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 1.66ε (Mean = 0.48ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 1.52ε (Mean = 0.357ε)</span>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Elliptic Integral Jacobi Zeta: Random Data
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 0ε (Mean = 0ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 2.99ε (Mean = 0.824ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 3.96ε (Mean = 1.06ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 3.89ε (Mean = 0.824ε)</span>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Elliptic Integral Jacobi Zeta: Large Phi Values
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 0ε (Mean = 0ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 2.92ε (Mean = 0.951ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 3.05ε (Mean = 1.13ε)</span>
                </p>
              </td>
<td>
                <p>
                  <span class="blue">Max = 2.52ε (Mean = 0.977ε)</span>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h5>
<a name="math_toolkit.ellint.jacobi_zeta.h3"></a>
        <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.testing"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.testing">Testing</a>
      </h5>
<p>
        The tests use a mixture of spot test values calculated using values calculated
        at <a href="http://www.wolframalpha.com/" target="_top">Wolfram Alpha</a>, and random
        test data generated using MPFR at 1000-bit precision and a deliberately naive
        implementation in terms of the Legendre integrals.
      </p>
<h5>
<a name="math_toolkit.ellint.jacobi_zeta.h4"></a>
        <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.implementation"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.implementation">Implementation</a>
      </h5>
<p>
        The implementation for Z(φ, k) first makes the argument φ positive using:
      </p>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="serif_italic"><span class="emphasis"><em>Z(-φ, k) = -Z(φ, k)</em></span></span>
        </p></blockquote></div>
<p>
        The function is then implemented in terms of Carlson's integral R<sub>J</sub>
using the
        relation:
      </p>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../equations/jacobi_zeta.svg"></span>

        </p></blockquote></div>
<p>
        There is one special case where the above relation fails: when <span class="emphasis"><em>k
        = 1</em></span>, in that case the function simplifies to
      </p>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="serif_italic"><span class="emphasis"><em>Z(φ, 1) = sign(cos(φ)) sin(φ)</em></span></span>
        </p></blockquote></div>
<h6>
<a name="math_toolkit.ellint.jacobi_zeta.h5"></a>
        <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.jacobi_zeta_example"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.jacobi_zeta_example">Example</a>
      </h6>
<p>
        A simple example comparing use of <a href="http://www.wolframalpha.com/" target="_top">Wolfram
        Alpha</a> with Boost.Math (including much higher precision using Boost.Multiprecision)
        is <a href="../../../../example/jacobi_zeta_example.cpp" target="_top">jacobi_zeta_example.cpp</a>.
      </p>
</div>
<div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ellint_d.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="heuman_lambda.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
